Summary

• Adds support for structuredContent in MCP tool results.
• Returns full CallToolResult from MCPServer#callTool (previously returned content[]).
• Adds useStructuredContent option to MCP server constructors (stdio, streamable-http, SSE), default false to preserve backward compatibility.
• Updates mcpToFunctionTool to include structuredContent in tool outputs when enabled.
• Closes Support structureOutput from MCP server tools #468.
• Parity with Python feature: MCP: add support for tool_result.structuredContent openai-agents-python#1150.
• Fixes TypeScript compilation errors (TS2352) in MCP server shims that prevented builds from completing.

Motivation

Previously, MCP server callTool only returned result.content. If a tool returned only structuredOutput, agents saw an empty array. This PR brings parity with the Python SDK by exposing structuredContent and providing a toggle to control inclusion in tool outputs.

Changes

• API: MCPServer#callTool(...) now returns CallToolResult (full object: { content, structuredContent? }).
• Option: useStructuredContent?: boolean added to all MCP server options and stored on base classes. Default false to avoid duplicate data when servers include structured output inside content.
• Composition in mcpToFunctionTool:
  • Default (flag off):
    • Single content item → return that item object
    • Multiple content items → return array of items
  • With useStructuredContent true:
    • Single content item → return [contentItem, structuredContent]
    • Multiple content items → append structuredContent to the array
    • No content → return structuredContent object
• No stringification: We keep JS outputs as objects/arrays to avoid forcing downstream JSON.parse. This differs from Python’s string concatenation but preserves capability parity and improves ergonomics/perf in JS.

Before/After

Before

// Returned only content[]
const content = await server.callTool('tool', args); // [] when tool only returned structuredOutput

After

// Returns full object
const result = await server.callTool('tool', args);
// result: { content: [...], structuredContent?: any }

// Default (useStructuredContent: false)
// Single content → object; multiple → array

// With useStructuredContent: true
const server = new MCPServerStdio({ command: 'my-mcp', useStructuredContent: true });
// Single content + structured → [contentItem, structuredContent]
// Only structured → structuredContent object

Tests

• Added packages/agents-core/test/mcpStructuredContent.test.ts:
  • Default off: single content returns the item object.
  • With flag true:
    • Single content + structured → array with structured appended.
    • No content + structured → structured object.
    • Multiple content + structured → array with structured appended.
• Updated mcpToolFilter.integration.test.ts stub to return { content: [...] }.
• All tests pass: 393 tests across 62 files.

Docs

• Added a section to packages/agents-core/README.md documenting useStructuredContent, the new callTool return type, and rationale for not stringifying.

Breaking Impact

• Minimal breaking change: Only affects advanced users who directly call MCPServer#callTool and expect an array return type.
• Behavioral outputs for mcpToFunctionTool remain backward-compatible by default (objects/arrays), with optional structuredContent inclusion when enabled.

Checklist

• Builds and full test suite pass
• Docs updated
• Changeset added (patch bump for @openai/agents-core)
• Linked to issue Support structureOutput from MCP server tools #468 and Python PR parity